Roc Toolkit internal modules
Roc Toolkit: real-time audio streaming
Loading...
Searching...
No Matches
iframe_decoder.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2017 Roc authors
3 *
4 * This Source Code Form is subject to the terms of the Mozilla Public
5 * License, v. 2.0. If a copy of the MPL was not distributed with this
6 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
7 */
8
9//! @file roc_audio/iframe_decoder.h
10//! @brief Audio frame decoder interface.
11
12#ifndef ROC_AUDIO_IFRAME_DECODER_H_
13#define ROC_AUDIO_IFRAME_DECODER_H_
14
15#include "roc_audio/units.h"
16#include "roc_core/stddefs.h"
17#include "roc_packet/packet.h"
18#include "roc_packet/units.h"
19
20namespace roc {
21namespace audio {
22
23//! Audio frame decoder interface.
25public:
26 virtual ~IFrameDecoder();
27
28 //! Get decoded stream position.
29 //!
30 //! @returns
31 //! the position of the next sample that will be retrieved by read().
32 //!
33 //! @remarks
34 //! The decoded stream position is affected by begin(), read(), and shift() methods.
35 //! begin() changes it according to the provided frame position, however it depends
36 //! on the implementation how exactly. read() and shift() increase it by the number
37 //! of samples they returned.
38 virtual packet::timestamp_t position() const = 0;
39
40 //! Get number of samples available for decoding.
41 //!
42 //! @returns
43 //! number of available samples per channel, or zero if there are no more
44 //! samples in the current frame, or if begin() was not called yet.
45 //!
46 //! @remarks
47 //! The number of samples available is affected by begin(), read(), and shift(),
48 //! and end() methods. begin() resets it according to the provided frame size,
49 //! however it depends on the implementation how exactly. end() resets it to zero.
50 //! read() and shift() decrease it by the number of samples they returned.
51 virtual packet::timestamp_t available() const = 0;
52
53 //! Start decoding a new frame.
54 //!
55 //! @remarks
56 //! After this call, read() will retrieve samples from given @p frame_data, until
57 //! @p frame_size bytes are read or end() is called.
58 //!
59 //! @note
60 //! @p frame_position defines the position of the frame in the encoded stream.
61 //! Decoder updates the decoded stream possition according to @p frame_position,
62 //! but not necessary to the same value. Encoded and decoded stream positions
63 //! may be slightly different, depending on the codec implementation.
64 virtual void begin(packet::timestamp_t frame_position,
65 const void* frame_data,
66 size_t frame_size) = 0;
67
68 //! Read samples from current frame.
69 //!
70 //! @b Parameters
71 //! - @p samples - buffer to write decoded samples to
72 //! - @p n_samples - number of samples to be decoded per channel
73 //! - @p channels - channel mask of the samples to be decoded
74 //!
75 //! @remarks
76 //! Decodes samples from the current frame and writes them to the provided buffer.
77 //!
78 //! @returns
79 //! number of samples decoded per channel. The returned value can be fewer than
80 //! @p n_samples if there are no more samples in the current frame.
81 //!
82 //! @pre
83 //! This method may be called only between begin() and end() calls.
84 //!
85 //! @note
86 //! Encoded and decoded channel masks may differ. If the decoded frame has
87 //! extra channels, they are ignored. If it doesn't have some channels, these
88 //! channels are filled with zeros.
89 virtual size_t
90 read(sample_t* samples, size_t n_samples, packet::channel_mask_t channels) = 0;
91
92 //! Shift samples from current frame.
93 //!
94 //! @b Parameters
95 //! - @p n_samples - number of samples to shift per channel
96 //!
97 //! @remarks
98 //! Shifts the given number of samples from the left, as if read() was called
99 //! and the result was dropped.
100 //!
101 //! @returns
102 //! number of samples shifted per channel. The returned value can be fewer than
103 //! @p n_samples if there are no more samples in the current frame.
104 //!
105 //! @pre
106 //! This method may be called only between begin() and end() calls.
107 virtual size_t shift(size_t n_samples) = 0;
108
109 //! Finish decoding current frame.
110 //!
111 //! @remarks
112 //! After this call, the frame can't be read or shifted anymore. A new frame
113 //! should be started by calling begin().
114 virtual void end() = 0;
115};
116
117} // namespace audio
118} // namespace roc
119
120#endif // ROC_AUDIO_IFRAME_DECODER_H_
Audio frame decoder interface.
virtual size_t read(sample_t *samples, size_t n_samples, packet::channel_mask_t channels)=0
Read samples from current frame.
virtual void begin(packet::timestamp_t frame_position, const void *frame_data, size_t frame_size)=0
Start decoding a new frame.
virtual packet::timestamp_t available() const =0
Get number of samples available for decoding.
virtual size_t shift(size_t n_samples)=0
Shift samples from current frame.
virtual void end()=0
Finish decoding current frame.
virtual packet::timestamp_t position() const =0
Get decoded stream position.
float sample_t
Audio sample.
Definition: units.h:21
uint32_t timestamp_t
Audio packet timestamp.
Definition: units.h:46
uint32_t channel_mask_t
Bitmask of channels present in audio packet.
Definition: units.h:77
Root namespace.
Packet.
Various units used in audio processing.
Various units used in packets.
Commonly used types and functions.